System functions

Systemfunctions have in common they do some processing that results in a set of lines. Usually these set of lines are included in the template file. The result of a system function can be inserted everywhere in the text by typing:

                    $(function-name)

There are six system functions:

1. html_content_div: reads, evaluates and translates the text of a content section
2. html_breadcrumbs_div: creates breadcrumbs for a page
3. html_mainmenu_div: creates a navigation menu for the full page hierarchy of the website
4. html_pagemenu_div: creates a navigation menu for parts of the page hierarchy which are relevant for the current page
5. include_file: reads and evaluates the lines of a textfile in the template directory
6. link_to_page: returns a link to a page

1. Function: html_content_div

Txt2Site processes the content files sequentially. A content file consists of multiple content sections. A content section begins after a line beginning with <<<<< and ending with >>>>>. When this function is used, a content section is read from the current content file. Depending on the used markup language (variable page_format), the content section is translated to XHTML code and placed in a div-element.
If variables or functions are found in the content section, these are evaluated.
The resulting XHTML code looks like this:

  <div id="div_content1" class="t2s_content" >
     translated lines of a content section
  </div>  <!-- div_content1 --> 

You can insert a content section on a page of the website by typing on the right place in the template file:

                     $(html_content_div 99 eval)

Here the first argument 99 denotes a valid section number. The first argument indicates which section of the content file to use. Sections in the content file are numbered sequentially 1,2,3,... If you do not give an argument for this function, then default section 1 is assumed.
The resulting div-element is identified by the name div_content99 where 99 denotes the section number. All generated div-elements have a common class t2s_content.
You can provide this function with an optional second argument. This argument is an evaluation flag. Values: eval or noeval. Default value: eval. If this argument has a value noeval then the evaluation of variables and functions within the content section is not performed.

2. Function: html_breadcrumbs_div

The result is a div-element with breadcrumbs for the current page. The breadcrumbs are computed using the location of the current page in the hierarchy of pages.
You can insert breadcrumbs in a page by typing in a template file or content file:

                     $(html_breadcrumbs_div)

An example of generated HTML code is:

  <div id="div_breadcrumbs">
     <a class="level_0" href="../../index.html" > Home </a> &gt; 
     <a class="level_1" href="../index.html" > Animals </a> &gt; 
     <a class="level_2" href="./index.html" > Mammals </a> &gt; 
     <a class="level_2 selected" href="./monkey.html" > Monkey </a> 
  </div>  <!-- div_breadcrumbs --> 

This code is generated for the page called Monkey for which the class is set to selected. Pagenames used in the a elements are created using the name of the content directories as breadcrumbs.
The name of the home page is read from the variable home_title.
If no default file is present in a content directory, the breadcrumb is shown but has an empty reference.
By using a stylesheet this HTML can be displayed horizontally as:
Home > Animals > Mammals > Monkey

3. Function: html_mainmenu_div

The result is a div-element with HTML code for a navigation menu. The navigation menu reflects the complete page hierarchy of the website. The HTML code is roughly the same for each page. Except for the current page, the class for its a-element and li-element is selected.
Hierarchy level numbers for li-elementen and ul-elementen are designated as class names. A stylesheet can be used to display the page hierarchy as you wish.
You can insert this menu in the pages of the website by typing on the right place in a template file or content file:

                      $(html_mainmenu_div)

An example of generated HTML code is:

  <div id="div_mainmenu"  class="t2s_mainmenu" >
     <ul class="level_0" >
        <li class="level_0" > <a class="" href="../../index.html" > Home </a> </li>
        <li class="level_0" > <a class="" href="../index.html" > Animals </a>  
        <ul class="level_1" >
           <li class="level_1" > <a class="" href="./index.html" > Mammals </a>  
           <ul class="level_2" >
              <li class="level_2" > <a class="" href="./monkey.html" > Monkey </a> </li>
              <li class="level_2 selected" > <a class="selected" href="./lion.html" > Lion </a> </li>
           </ul>
           </li>
           <li class="level_1" > <a class="" href="../birds/index.html" > Birds </a>  
           <ul class="level_2" >
              <li class="level_2" > <a class="" href="../birds/starling.html" > Starling </a> </li>
              <li class="level_2" > <a class="" href="../birds/sparrow.html" > Sparrow </a> </li>
           </ul>
           </li>
        </ul>
        </li>
        <li class="level_0 " > <a class="" href="../../plants.html" > Plants </a> </li>
     </ul>
  </div>  <!-- div_mainmenu -->  

This code is generated for the page called Lion for which the class is set to selected. Pagenames used in the a elements are created using the name of the content file or content directory. If no default file is present in a content directory, the menu item is shown but has an empty reference.
If the home page exists, it can be made hidden by the variable omit_home_from_main_menu.
The name of the home page is read from the variable home_title.

The mainmenu reflects the complete page hierarchy. It is usual to display only a part of the menu and expand the menu by hovering over elements. You can do this by using the stylesheet. Depending on the used stylesheet you can display the menu as you wish: horizontal, vertical, .. If you would display all the items of the menu, it looks like this:

  Home
  Animals
      Mammals
          Monkey
          Lion
      Birds
          Starling
          Sparrow
  Plants

Hint: the mainmenu-function can also be used to create a sitemap page.

Excluding menu items

You can exlude items from the menu using the optional EXCLUDE argument. As an example you can call the mainmenu by the statement:

                      $(html_mainmenu_div EXCLUDE 010 240 300)

The effect is that menu items of content files or content directories with prefixes 010, 240 and 300 are excluded from the mainmenu. If you exclude a content directory, also its childs are excluded from the menu. You can specify as many prefixes you want.
Exclude the items you want by carefully name your prefixes in the format 999_ which at the same time meets your sorting needs.
For example you can split your menu in two parts by calling the mainmenu twice. In the first call you exclude the second part and in the second call you exclude the first part.

4. Function: html_pagemenu_div

The result is a div-element with HTML code for a navigation menu. This navigation menu reflects only a part of the page hierarchy of the website. Only relevant parts for the current page are generated. So the HTML code differs for each page. For the current page, the class for its a-element and li-element is selected.
Hierarchy level numbers for li-elementen and ul-elementen are designated as class names. A stylesheet can be used to display the page hierarchy as you wish.
You can insert this menu in the pages of the website by typing on the right place in a template file or content file:

                     $(html_pagemenu_div)

An example of generated HTML code is:

  <div id="div_pagemenu"  class="t2s_pagemenu" >
     <ul class="level_0" >
        <li class="level_0" > <a class="" href="../../index.html" > Home </a> </li>
        <li class="level_0 expanded" > <a class="" href="../index.html" > Animals </a>  
        <ul class="level_1" >
           <li class="level_1 expanded" > <a class="" href="./index.html" > Mammals </a>  
           <ul class="level_2" >
              <li class="level_2" > <a class="" href="./monkey.html" > Monkey </a> </li>
              <li class="level_2 selected" > <a class="selected" href="./lion.html" > Lion </a> </li>
           </ul>
           </li>
           <li class="level_1" > <a class="" href="../birds/index.html" > Birds </a> </li>
        </ul>
        </li>
        <li class="level_0 " > <a class="" href="../index.html" > Plants </a> </li>
     </ul>
  </div>  <!-- div_pagemenu -->  

This code is generated for the page called Lion for which the class is set to selected. Pagenames used in the a elements are created using the name of the content file or content directory. If no default file is present in a content directory, the menu item is shown but has an empty reference.
If the home page exists, it can be made hidden by the variable omit_home_from_main_menu.
The name of the home page is read from the variable home_title.

This pagemenu is only expanded for the current page. This make this menu suitable to display all the menu items. The effect is that only the relevant parts of the navigation is visible. It keeps the stylesheet simple. Displaying all the items of the menu looks like this:

  Home
  Animals
      Mammals
          Monkey
          Lion
      Birds
  Plants

Excluding menu items

You can exlude items from the pagemenu using the EXCLUDE argument. See the description for the mainmenu function.

5. Function: include_file

This function reads the lines of a file in the template directory. It returns these lines after evaluating variables and functions (optional).
This function can be used to include a file in the template file or in a content section. Can be used on the whole site. So repeating sets of lines can be maintained easier.

You can use the include function by typing on the right place in a template file or content file:

                     $(include_file filename eval)

This function has two arguments: filename and an evaluation flag.
The filename denotes an existing textfile in the template directory.
The evaluation flag has values: eval or noeval. Default value: eval. If this argument has a value noeval then the evaluation of variables and functions is not performed for the lines found in the included file.

Examples for use:

1. The header and configuration area of Txt2Tags text is often the same for all content sections. Put these lines in a file in the template directory. Call this function with this file at locations where these lines are required. No evaluation is necessary.
2. If you have different template files with the same footer content, you can put the footer content in a separate file and include this file in the template files.

6. Function: link_to_page

This function returns a reference to the page indicated by the argument. The reference is relative to the current page. The argument is a prefix of a content file.
A reference is returned for the page of the content file which matches the prefix.
If the argument is HOME (not case sensitive), a reference to the homepage is returned.
If more than one match is found, a random choice is made.
If no match is found, a reference to the current page is returned.

The matching is not influenced by a trailing documentation string in the argument.
So for both arguments 831 and 831_Produce a reference to the same page is returned.
And for all arguments home, Home, HOME and Homepage a reference to the homepage is returned.

This function is mostly used with the html a-tag.
Examples:

    <a href="$(link_to_page 202_Contact Page)" > Contact Page </a> 
    <a href="$(link_to_page Homepage)" > Welcome </a> 

When using this function, carefully name your prefixes of the content files. Although prefixes are freely to choose and need not be unique, keep in mind why you want to use prefixes.
Prefixes can be used to sort menu items, to exclude menu items and to use this function to make a link to a page. In the latter case you probably want the prefix is unique for the whole site.